home *** CD-ROM | disk | FTP | other *** search
/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / lib / c / host / RCS / Host.man,v < prev    next >
Encoding:
Text File  |  1992-06-05  |  6.3 KB  |  237 lines
  1. head     1.5;
  2. branch   ;
  3. access   ;
  4. symbols  ;
  5. locks    jhh:1.5; strict;
  6. comment  @@;
  7.  
  8.  
  9. 1.5
  10. date     90.12.13.00.08.00;  author kupfer;  state Exp;
  11. branches ;
  12. next     1.4;
  13.  
  14. 1.4
  15. date     90.10.31.22.34.58;  author jhh;  state Exp;
  16. branches ;
  17. next     1.3;
  18.  
  19. 1.3
  20. date     90.01.02.14.20.23;  author shirriff;  state Exp;
  21. branches ;
  22. next     1.2;
  23.  
  24. 1.2
  25. date     89.06.08.09.27.50;  author mendel;  state Exp;
  26. branches ;
  27. next     1.1;
  28.  
  29. 1.1
  30. date     88.12.30.15.05.35;  author ouster;  state Exp;
  31. branches ;
  32. next     ;
  33.  
  34.  
  35. desc
  36. @@
  37.  
  38.  
  39. 1.5
  40. log
  41. @HostByID => Host_ByID (in NAME section).
  42. @
  43. text
  44. @'\" $Header: /sprite/src/lib/c/host/RCS/Host.man,v 1.4 90/10/31 22:34:58 jhh Exp Locker: kupfer $ SPRITE (Berkeley)
  45. .so \*(]ltmac.sprite
  46. .HS Host lib
  47. .BS
  48. .SH NAME
  49. Host_ByName, Host_ByID, Host_ByNetAddr, Host_ByInetAddr, Host_SetFile,
  50. Host_Start, Host_Next, Host_End \- return information about Sprite machines
  51. .SH SYNOPSIS
  52. .nf
  53. \fB#include <host.h>\fR
  54. .sp
  55. Host_Entry *
  56. \fBHost_ByName\fR(\fIname\fP)
  57. .sp
  58. Host_Entry *
  59. \fBHost_ByID\fR(\fIspriteID\fP)
  60. .sp
  61. Host_Entry *
  62. \fBHost_ByNetAddr\fR(\fIaddrType, addrPtr\fP)
  63. .sp
  64. Host_Entry *
  65. \fBHost_ByInetAddr\fR(\fIinetAddr\fP)
  66. .sp
  67. int
  68. \fBHost_SetFile\fR(\fIfileName\fP)
  69. .sp
  70. int
  71. \fBHost_Start\fR()
  72. .sp
  73. Host_Entry *
  74. \fBHost_Next\fR()
  75. .sp
  76. void
  77. \fBHost_End\fR()
  78. .sp
  79. int
  80. \fBHost_Stat\fR(\fIstatPtr\fR)
  81. .SH ARGUMENTS
  82. .AS "struct in_addr" inetAddr
  83. .AP char *name in
  84. The name of a Sprite host for which information is desired.
  85. .AP int spriteID in
  86. The Sprite ID of the host for which information is desired.
  87. .AP Host_NetType addrType in
  88. Type of network the host is on.  Also defines the type of \fIaddrPtr\fR.
  89. Only \fBHOST_ETHER\fR and \fBHOST_INET\fR are defined right now.
  90. .AP char *addrPtr in
  91. The local network address of the host for which
  92. information is desired. The actual type used is based on the value of
  93. \fIaddrType\fP.  See the types defined below for the \fInetAddr\fR
  94. union in Host_Entry structures.
  95. .AP "struct in_addr" inetAddr in
  96. The internet address of the host for which information is desired.
  97. .AP char *fileName in
  98. The name of a host-description file.
  99. .AP struct stat *statPtr
  100. Pointer to stat structure for host database file.
  101. .BE
  102. .SH DESCRIPTION
  103. These functions are used to learn about hosts on the local Sprite network.
  104. These functions cause the host description file to be opened.
  105. \fBHost_End()\fR must be called to close the file.
  106. .PP
  107. A Host_Entry structure is defined as follows:
  108. .DS
  109. .ta 1c 2c 3c 4c 5c 6c 7c 8c 9c 10c
  110. typedef struct {
  111.     char            *name;    /* Primary name */
  112.     char            **aliases;    /* Other names (null-terminated array) */
  113.     int            id;        /* Sprite ID */
  114.     struct in_addr        inetAddr;    /* Internet address */
  115.     Host_NetType        netType;    /* Network used to connect to host */
  116.     union {
  117.         unsigned char        etherAddr[HOST_ETHER_ADDRESS_SIZE];
  118.                             /* Address for \fInetType\fR \fBHOST_ETHER\fR 
  119.                                and gateway address for \fBHOST_INET\fR */
  120.     } netAddr;                    /* Address in that network */
  121.     char                *machType;    /* Machine type, such as ``sun3''. */
  122. } Host_Entry;
  123. .DE
  124. The Host_Entry structures returned by the routines are statically allocated
  125. and may change on the next call to any \fBHost_\fR procedure.  Be sure to copy
  126. out any information you need before calling a \fBHost_\fR procedure again.
  127. .PP
  128. \fBHost_ByName()\fR returns a Host_Entry based on the name or alias of a host.
  129. .PP
  130. \fBHost_ByID()\fR returns a Host_Entry for the host with the given sprite ID.
  131. .PP
  132. \fBHost_ByNetAddr()\fR returns the Host_Entry for the host with the given
  133. local-area-network address.  The only type of network address currently
  134. supported is \fBHOST_ETHER\fR, so the address must always have the
  135. format defined for \fIetherAddr\fR in Host_Entry structures.
  136. .PP
  137. \fBHost_ByInetAddr()\fR returns the Host_Entry for the host with the given internet
  138. address.
  139. .PP
  140. \fBHost_SetFile()\fR specifies a different host information
  141. file to use (the file normally used
  142. is \fB/etc/spritehosts\fR).
  143. .PP
  144. \fBHost_Start()\fR opens the current host-description file (if it isn't
  145. already open), while \fBHost_End()\fR closes
  146. it.  The \fBHost_By\fR... procedures automatically call \fBHost_Start\fR.
  147. .PP
  148. \fBHost_Next()\fR may be used to step through the current host-description file.
  149. The host-description file must have been opened using \fBHost_Start()\fR or one of the
  150. \fBHost_By\fR functions.
  151. .PP
  152. \fBHost_Stat()\fR is used to get the statistics for the host-description file.
  153. See the \fBstat()\fR man page for details on the stat structure.
  154. \fBHost_Stat()\fR is
  155. useful if you are writing a daemon that wants to do something when
  156. the host-description file is updated. 
  157. The daemon can loop waiting for the modify time of the file to change.
  158. Make sure the host-description file is closed (use \fBHost_End()\fR) before
  159. the daemon waits, otherwise every machine running the daemon will have the
  160. host-description file open, causing lots of consistency traffic.
  161. .SH DIAGNOSTICS
  162. \fBHost_SetFile()\fR,\fBHost_Start()\fR and \fBHost_Stat()\fR
  163. return zero if all went well.  Otherwise
  164. they return -1 and the \fBerrno\fR variable contains additional information
  165. about what error occurred.
  166. \fBHost_Next()\fR returns NULL on end-of-file or error. \fBHost_ByName()\fR,
  167. \fBHost_ByID()\fR,
  168. \fBHost_ByNetAddr()\fR and \fBHost_ByInetAddr()\fR return NULL if
  169. the given host could not be found.
  170. .SH FILES
  171. /etc/spritehosts    The default host-description file.
  172. .SH KEYWORDS
  173. hostname, internet address, local net, machine type, sprite ID
  174. @
  175.  
  176.  
  177. 1.4
  178. log
  179. @added Host_Stat()
  180. @
  181. text
  182. @d1 1
  183. a1 1
  184. '\" $Header: /sprite/src/lib/c/host/RCS/Host.man,v 1.3 90/01/02 14:20:23 shirriff Exp Locker: jhh $ SPRITE (Berkeley)
  185. d6 1
  186. a6 1
  187. Host_ByName, HostByID, Host_ByNetAddr, Host_ByInetAddr, Host_SetFile,
  188. @
  189.  
  190.  
  191. 1.3
  192. log
  193. @Put all procedure names into header line.
  194. @
  195. text
  196. @d1 1
  197. a1 1
  198. '\" $Header: /sprite/src/lib/c/host/RCS/Host.man,v 1.2 89/06/08 09:27:50 mendel Exp Locker: shirriff $ SPRITE (Berkeley)
  199. d35 3
  200. d56 2
  201. d108 10
  202. d119 2
  203. a120 1
  204. \fBHost_SetFile()\fR and \fBHost_Start()\fR return zero if all went well.  Otherwise
  205. @
  206.  
  207.  
  208. 1.2
  209. log
  210. @Added "inet" routes to the hostfile.
  211. @
  212. text
  213. @d1 1
  214. a1 1
  215. '\" $Header: /sprite/src/lib/c/host/RCS/Host.man,v 1.1 88/12/30 15:05:35 ouster Exp Locker: mendel $ SPRITE (Berkeley)
  216. d6 2
  217. a7 1
  218. Host \- return information about Sprite machines
  219. @
  220.  
  221.  
  222. 1.1
  223. log
  224. @Initial revision
  225. @
  226. text
  227. @d1 1
  228. a1 1
  229. '\" $Header: /sprite/doc/ref/lib/c/RCS/Host,v 1.3 88/12/15 09:22:55 ouster Exp $ SPRITE (Berkeley)
  230. d42 1
  231. a42 1
  232. Only \fBHOST_ETHER\fR is defined right now.
  233. d69 2
  234. a70 1
  235.                             /* Address for \fInetType\fR \fBHOST_ETHER\fR */
  236. @
  237.